package com.tgd.RingtoneContactManager;

/**
 * This interface will be used by the client to access information about a
 * ringtone.
 */
public interface Ringtone {
    /**
     * This enumeration is used to determine how the ringtones should be
     * filtered.
     */
    static enum Filter {
        /**
         * Given to
         * {@link DAO#getRingtones(DAO.Ringtone.Filter, DAO.Ringtone.Sort)} so
         * the return list contains all ringtones.
         */
        ALL,
        /**
         * Given to
         * {@link DAO#getRingtones(DAO.Ringtone.Filter, DAO.Ringtone.Sort)} so
         * the return list contains only ringtones that are assigned to a
         * contact. The default ringtone is also returned.
         */
        WITH_CONTACT,
        /**
         * Given to
         * {@link DAO#getRingtones(DAO.Ringtone.Filter, DAO.Ringtone.Sort)} so
         * the return list contains only ringtones that do not have any contacts
         * assigned. The default ringtone is not returned.
         */
        WITHOUT_CONTACT,
    }

    /**
     * This enumeration is used to determine how the ringtones should be sorted.
     */
    static enum Sort {
        /**
         * Given to
         * {@link DAO#getRingtones(DAO.Ringtone.Filter, DAO.Ringtone.Sort)} so
         * the returned list is sorted by the number (descending) of contacts
         * that use the ringtone. Ringtones that have identical amounts of
         * contacts are sorted by ringtone name. If name and contact amount are
         * equal the sort is undefined.
         */
        CONTACT_COUNT,
        /**
         * Given to
         * {@link DAO#getRingtones(DAO.Ringtone.Filter, DAO.Ringtone.Sort)} so
         * the returned list is sorted by the name of the ringtone. Sort order
         * for 2 identical names is undefined.
         */
        NAME,
    }

    /**
     * @return The contacts that use this ringtone.
     */
    public Contact[] getContacts();

    /**
     * @return The id of the ringtone.
     */
    public String getId();

    /**
     * @return The name of the ringtone.
     */
    public String getName();

    /**
     * @return The number of contacts that use this ringtone.
     */
    public int getNumContacts();

    /**
     * TODO THIS MAY NEED HIDDEN FROM THE INTERFACE, THE CLIENT SHOULDN'T CARE.
     * Should the DAO handle playing ringtones?
     * 
     * @return The position of this ringtone in the RingtoneManager cursor.
     */
    public int getPosition();

    /**
     * @return Whether or not this is the default ringtone.
     */
    public boolean isDefault();
}
